This is a program designed to "play" disc-based sound, PICT and movie files in the order, timing and duration specified by a simple script (which the user creates). It was originally written for psychological/functional neuroimaging presentation of stimuli. This archive contains a fully working demonstration version whose only limitation is a time-limit (5-10 minutes or so).
If you like it and would like to update your version immediately to the fully working version, then please follow the instructions in the "Registering" topic of the on-line help (look under the Apple menu for MacStim Help...). The current cost and how to register is fully explained there.
Overview
========
The general plan of its use is as follows:
1. An experimenter requires to present some stimuli using the Macintosh.
2. They draw their stimuli in a drawing application (eg Canvas or MacDraw etc) then save them as PICT files (B&W or color).
3. They similarly create, record or download sound (as 'sfil' files) & QuickTime™ movie files in the appropriate applications. MacStim recognizes 1 sound per file (eg as created by SoundMaster™).
4. These are then all placed in the same folder so MacStim can find them.
5. After launching MacStim, they create a new script which determines how MacStim uses the resources just created. A script is just a text file which MacStim can interpret for its special needs. It has fields, including times to display the resources (down to 1/60th of a second), filenames, the type of stimulus (sound, movie or PICT), the event which the experimenter wants from the user to indicate their response (and record a reaction time from stimulus onset eg. mouse or a key event). Times for presentation of PICTs are accurate to 16 or so milliseconds (one screen refresh).
6. They set any special preferences they want for that script eg. all pictures should be left on until the next one (avoiding unsightly flashing of pictures during transitions), setting the display's monitor (if on a multiple monitor system), or the background display color etc.
7. They "run" the script to test it and debug it before saving it for use with subjects.
How to get help
==============
Full instructions appear in the applications on-line help which is accessed from the main control window or Apple menu. There are control structures for repeating specified blocks of trials (a "trial" is one single line), specifying which blocks of trials to randomize, specification of blocks of trials for animations, horizontal and vertical coordinates from center to move stimuli around on the screen, and much more. Serial port messages can be sent out for each phase of a trial to allow synchronizing with externally driven devices. MacStim aims to be flexible, accurate and powerful, but you will need to be the final arbiter! There are also display options, allowing flexible control over the length of stimuli, background color, scaling of PICTs, etc.
When you open the Help window, you can print all of the contained text instructions using the window's Print All command (under the small "File" menu at its top left).
Compatibility & Stability
=======================
It should be stable on all Mac models running system 6.0.5 or above and works best on system 7 or higher, but if there are any problems please contact us.
Preloading PICTs & sounds
========================
MacStim will attempt to preload all PICTs and sounds unless you precede their resource type by a dash (ie -p means don't bother preloading that picture file, wait until it's needed during the experiment). In any event, large 24 bit PICT images on a 21 inch screen, should be flight-tested since you will need sufficient RAM memory to store the offscreen structures. There are some tips given for solving this problem in the on-line help.
DEMONSTRATION VERSION:
========================
If you have not yet registered your copy of MacStim, then there are some limitations on how long you may use MacStim (between 5-10 minutes most likely). You may try MacStim out as many times as you like, but if you want to register it, then please read and follow the instructions in the on-line help entitled Registering…. The purchase price can be sent to me (there is no shipping and handling if you are just requesting a password to "unlock" your copy). If you don't wish to register, then thanks for trying MacStim, and if you have any specific dislikes, that I might be able to fix then please contact me about your specific needs.
Upgrading from earlier versions
=============================
NOTE: if you are upgrading from an earlier version of MacStim, then you note that the old preferences both within your system folder and for each script may require updating (due to added preferences options). If this is the case, then you will be notified, but the old preference settings will be lost and you must reset them if you want the script to run as before. Once you have reset the preferences, then they will be remembered after you save the script to disc. You will usually have to go through the registration procedure again so don't lose your registration details. If you do, please contact me for updated ones. See the on-line help on how to set your preferences.
Current Address: 80 Roden St, West Melbourne, 3003, Victoria, Australia, phone (613) 9329-9981, Fax 613-9496-4065.
Please refer to the on-line documentation for warranties, guaranties and legal notes.
Please enjoy!
David Darby November 1995
Evolutionary Log
v1.4
#Continuous play back option
#No screen refresh option implemented
#Color icons & buttons with 3D look & feel added
#Active cursor display for experimenter feedback
#Default RAM partition to 900K (to cover standard 13" color monitor)
v1.5
#Serial port signals sent out modem port if connected to compatible device.
#Help file adjusted to reflect new changes
#User adjustment of integers sent at preSecs and testSecs start and end.
v1.6
#Serial port problem on PowerBooks fixed (they expect a hardware handshake as default behavior from the serial port, so hung indefinitely awaiting this). Port was left disabled so program hung on subsequent application initializations. Hardware handshake now set to 0 initially.
v1.9
#versions 1.7-1.8 were never released due to major enhancements & rewriting of code.
#preloading of PICTs implemented
#new test event loop without WaitNextEvent so no time is given up to background applications (unless user events are to be trapped).
#full screen display implemented
#serial port output enhanced
#preferences' options expanded
#color depth setting support (seeks deepest device & recalls its depth)
#color background support
#"none" option for stimulus or background resources
#script support for repetitions until a predetermined elapsed time
#attempted use of extended time manager aborted (for the present)
#preloading of next sound to be played was implemented
#nothing event type added (for presentations not requiring user feedback)
#end of experiment recording of user reaction times implemented (optional)
#support for background sounds implemented
#trial help pop up added to main control window
#on-line help updated (topics menu added)
v2.0.1
#expansion of trial types to include "pause", "random" (with up to 50 subtrials), "block" (ie a block of animation pictures and/or sounds), as well as the original single trial.
#randomization of time periods within a trial enabled (specified by a negative number), available for all time periods except the repetition period.
#improved dialog window for resource finder and entering trials.
#correction of timing bugs (though still uses ticks rather than time manager) and as drift-free as ticks can be!
#reinsertion of premature trial termination or indefinite trial duration awaiting user input.
#sounds now play correctly (deallocated sound handle problem fixed).
#major code rewrite to support modularity of expansion.
#serial port options enhanced (to overcome express modem control of serial port!).
#on-line help file window expanded and updated.
#default center for the screen can be moved to correct for unusual screen positions.
#minimum response time can be specified (to exclude non-physiological stop events).
v2.0.2
#Sound manager routines upgraded to ensure correct single channel play on all models.
#Pre seconds of zero now supported.
#Miscellaneous bugs due to more modular programming of 2.0.1 fixed.
v2.0.3
#Name altered from PsychStim to McStim for no good reason.
#Sounds now also preloaded to allow rapid onset and offset without the need for disc loading prior to playback.
#Sounds now all play asynchronously and as click free as I can make them.
#Error strings moved into the resources
#Limited support for National Instruments Board included (this feature currently crashes if you select this option & try to run without such a board!).
#A number of board signals to be ignored can be set if such a board exists.
#The screen on which to display the pictures is now selectable in the preferences.
v2.0.5
#Reaction times now accumulated in their own text buffer and viewed in separate log window (one line per trial so random trial order can be viewed at experiment completion).
#On-line help put into separate window and updated/extended. Several Notes fields included to allow user to document their own experiments.
#Dual monitors (or more) now supported via pop up menu in Preferences dialog. You can run the script on one monitor and the experiment on another.
#National Instruments Board can optionally be set to trigger at the start of the experiment only (rather than 2.0.4 wherein it needed to re-trigger after each playing of the script). (Pop up replaced the check box in preparation for other boards).
#Window menu added (to allow showing of hidden windows easily).
#Alert dialog text area expanded.
#Preferences: incorporate version number, with automatic deletion of older preferences files at startup.
v2.0.6
#Add-on board triggering fixed (minor problem with new Preferences pop up menu).
#A "Don't hide cursor" check box option has been added to allow visualization of the cursor (if the subject is required to click on certain parts of the screen). Mouse locations in global coordinates are now recorded when the user clicks correctly.
#First background PICT (if present) will show if an add-on board is present whilst awaiting the correct number of trigger pulses.
v2.0.7
#Preferences dialog revamped to allow for better visual presentation and expansion.
#MacStim now actively seeks the presence of NuBus boards, popup in Boards option in preferences dialog now lists the filled slots, can be selected. Cannot be selected if no board is present.
#Triggering by an installed & selected NuBus (currently National Instruments) board can be used in script (via "t" or "T" in the stop event field) to terminate a stimulus (making it possible to trigger the board eg by a user event) other than by the mouse or a key press.
#A bug in random and block timing fixed (set port before clear window)
#A bug fixed when a file name did not exist for a specified picture resource.
#Support for restarting an experiment without requiring to reload all the resources added (use command-0 ie zero, after pausing the experiment).
#Recording of triggered events puts the board trigger count after the reaction time.
v2.0.8
#FSSpec records are now used to make MacStim compatible with AV and PowerMacs. Full native optimization not yet implemented.
#Full optimization for rapid GWorld CopyBits operations finished making really fast animations possible.
#Size of largest PICT now used for all offscreen GWorlds (picts are automatically centered). Smaller PICTs use the background color (set in the Preferences Display option) for their GWorld before being drawn. This eliminates a step during playback and allows large (eg full screen 640*400 on my PowerBook) PICT animation even within 1 tick without drawing aberrations.
#PICT loading/RAM allocation deficiency errors made more informative.
#Resource-finder made more user-friendly & self-explanatory.
#Serial port (output and input of single characters) implemented.
#Test button added to Serial Setup view of Preferences dialog.
#Ability to resize scaled PICT (to full test screen or arbitrary size).
#Note about making block and random block rep time > 0.0 secs!
#Comment/Uncomment menu items added to Control menu.
v2.1.0
#QuickTime movie support added for background or stimulus resources. Note that performance is not as rapid initially for movies, and your combinations should always be tested to ensure they meet your timing requirements.
#Movie preview menu item added so movies can be viewed, and cut, copy, paste and scaling operations enabled for specific movies.
#Movie preferences view added for extra global movie control options.
#Uncoment comments with empty line bug fixed.
#On-line help updated to include movie controller and operation instructions.
#New contact details in Australia added.
v2.1.1
#Preferences crash finally tracked down. It occurs when non-National Instruments Boards are seen by the Slot Manager routines on opening the Preferences dialog. The SOffsetData ROM call crashes intermittently. This has now been isolated, such that it will only be called if there is a board present with the first letter 'N'. If there are still problems please tell me!
#File loading errors are better reported (name of missing or incorrect file is included in error message and first instance of the missing file is hilighted). This works for pictures and sounds. At present no check is made for the integrity of Movies, so please do trial runs just in case you get the file names wrong.
#Run selected lines menu option added for ease in debugging.
#On-line help updated.
v2.1.2
#Create script option enabled. Allows you to run a script, testing it completely (ie whether MacStim can load and find the files) completely but without running it, and instead write the order of the trials into a new script editor window. This is designed to let users create multiple scripts (eg with randomly ordered blocks) that they can re-use (eg in a Latin square design).
#When a new script editor is saved, the volume directory is now correctly remembered between script shifts allowing you to open multiple scripts based on multiple directories and then play them correctly consecutively (you must start them manually).
#Preferences settings now are saved with the script, and follow the active window changes (except for the monitors setting). If older version scripts are opened, their preferences settings are updated when they are saved.
#When there are no script editors open, using the Open item now creates a new script editor window rather than opening scripts into the Log window.
#A fixation point can now be added to all PICTs (see Preferences dialog: Display section).
v2.1.3
#Gave up on searching slots for their contents: too many crashes! Now user is responsible for determining whether a National Instruments Board is present and it must be in Slot 6 in the current version (until we rewrite the C ported library). It should not crash now during preferences display, but be warned that if you have this option set (which may happen inadvertently using a saved script from another lab which has such a board!) then you may get run time crashes! Will try to make this more general & user friendly by incorporating support for all National Instruments Boards (using their driver).
#Pause trials now can be triggered not only by mouse or key down events, but also serial or Nat Instruments Boards events. The serial event trigger defaults to any character (ie any specific byte (ie 8 bits)) read via the serial port (value of 0), but you can select any of the 9 digits to make this a selective trigger to the next stage of the trial. Experiment with mouse and key down events first before trying the serial ones though!
#Text only can be inserted directly into the script for display without needing to make up a PICT file. The Font, size, style and color are specified at the top of the script window for convenience. At present all instances of text must be the same FSSC characteristics.
#Vertical retrace manager support included. This is not yet optimal but has improved the picture flicker which was present using unsynchronized screen copybits operations. This can be switched on in the preferences dialog under display.
v2.1.4
#A major crash producing bug upon using or opening the Preferences dialog was definitely eliminated! This intermittently caused trashing of other memory addresses within the application and was very difficult to track down. It now should be stable on all models of mac including AV, and PowerPCs (address 200 offset in myPrefs).
#Overhead problems with starting timing immediately after dismissing the initiation alert were solved by using a flashing mouse button cursor to indicate the experiment will begin after clicking the mouse.
#Serial port inconsistencies fixed. Printer and modem ports can be selected in any order and tested for problems without crashes and working during experiments.
#When key events are the specified stop events, and recording of reaction times is enabled, MacStim will now record as many keys as are pressed until the end of the trial period.
v2.1.5
#Create scripts utility bugs fixed: last line of a script no longer continues in perpetuity, last trial times in a non-exact random block now are correctly marked. Note that if you have multiple lines in a random block ie several grouped lines (such as a prime and the a probe line), if the lines do not work out exactly (into your specified block repetition time), then they may split between primes and subsequent lines. This is especially true if you use the minus sign before a time to randomize it on the fly. There is little that can be done about this except to be aware, and to scrutinize your scripts to see if they can be removed or extended to make a complete group of linked trials.
#Adding resources to random trials no longer puts "s" instead of "r" for random trial type (bug introduced in 2.1.4).
#Control dialogs are now always shown on the main screen, ie the one with the menu bar. This is so you can show the stimuli on another screen but maintain control on the main screen. Hence in the preferences Display panel, when you select another screen, it only refers to stimuli.
#Large scripts: are now handled correctly (without a numeric overflow crash!). This was a problem when large scripts (eg 250 lines or more) were used with text only stimuli (which don't take up much RAM memory). I think there should only be a limit by available RAM now.
v2.1.6
#Major bug fix for serial and NuBus board triggered ending of stimulus period. This should fix the difficulty that was encountered when trying to get MacStim to respond to such termination events in some configurations.
#Voice activated support added. Voice activation level and recording now can be used. New controls added to preferences dialog: Timing & Events pane to document functionality and allow testing of the current configuration. Recorded sounds can be saved to disc (filenames are based on the current Mac clock time in seconds) in Finder format (playable by double clicking in system 7+) and their size can be specified in kilobytes.
#Session name feature added to script window. This allows unique subjects or test conditions to be named (up to 13 chars). Session name is put into the log window above the results for that trial and and incorporated into the recorded sound filename for easy identification.
#Since script preferences are embedded into all scripts (rather than being "global") any more, a new script's stored preferences will override the current global ones. Be aware that you may have to reset all preferences when this new version is used, including some that did not exist before. All sample scripts have been updated. Unique preferences are described in comment sections of these scripts for your reference.
#Stimulus presentation improved. PICTs, text & movies should display better, and background colors are correctly placed behind movies, pictures and text. CopyBits optimizations further improved. All samples tested fine. PICTs now all draw to offscreen gworld matching size of test window, then are copied directly to screen. Movies are placed in their own window which no longer is the full size of the screen (hence background color is correct).
#Animation is now possible using just a single picture (or text) and using the new fields hShift and vShift (horizontal and vertical shifts by pixels, ±10,000). See the Bouncing Ball script for an example. Movies can also be offset vertically and horizontally in the same way.
#PICTs now create their own offscreen environment matched exactly to their own dimensions. This means that (i) background rectangles are not required since the picts can be horizontally offset to any screen position, (ii) pre-flighting no longer occurs (speeding up loading of large scripts), (iii) errors during picture loading are probably due to insufficient RAM, (iv) RAM requirements can be lessened for small but multiple pictures.
#Horizontal & vertical flipping enabled (via Display pane in Preferences dialog). This will flip all picts that are shown but NOT movies or text since these are performed on the fly! Note that horizontal flipping on the fly is unbearable slow (on my test Macs anyway).
#VOX kilobyte limit fixed to be limited only by available RAM (short/long confusion).
#Timing inconsistencies and intermittent "freezes" due to Microseconds manipulations fixed using ticks pro term.
#On-line help updated
v2.1.7
#Scripts with more than 1000 lines were crashing due to a pascal array indexing limitation, which has now been extended to 30,000 lines. Hope this is enough Dara!
#Continuation request screen now correctly appears on the main monitor in a multiple monitor setup.
#Key press recording only occurs for trials in which it is requested
#The first line of stimulus text is now vertically centred as a default. If your specific text runs off the bottom of the screen, then you can use the horizontal and vertical shift offsets to correct for individual text blocks.
#Smoothness of movies improved by doubling the number of calls to the movie idling procs.
#PICTs (& sounds) can now be loaded on-the-fly if memory is short. You can specify that a picture is not loaded initially (ie does not have its own initial offscreen gWorld waiting to be used) by preceding its "p" resource type by a dash ie "-p". This picture will be checked for availability and size etc (ensuring it exists & can be loaded without error), and then discarded until the preceding trial's stimulus time when MacStim will attempt to load it (after showing the stimulus of that trial).
Please be aware of some caveats:
1. large files will take a relatively long time to load & make ready so these should not be in time critical script segments
2. rapid stimulus responses for the immediately preceding trial should also not be critical if the loading time is more than a hundred milliseconds or so (small pictures load in 10-40ms)
3. best performance occurs when all pictures can be preloaded
4. if memory is insufficient to load a needed picture, then already loaded pictures will be dumped first starting at the beginning of the alphabetical list of pictures
5. Loaded resources on the fly have a log entry to tell you what happened and how long it took. This is needed since you may not suspect that this occurred and may be helpful if your timings are not working out as suspected
6. You can work out how long it will take (roughly) to open the picture file, load its handle, and create its gWorld by using the new Control menu item "Compute Load Time".
7. Picture handles are not purged specifically by MacStim, so note that in some instances picture loading may be much more rapid than the computed times from scratch suggest. These should be regarded as worst-case estimates (but several readings should be taken to ensure you have a true indication of the slowest times).
#A new trial type, "continuous" specified by "c", created to allow continuous playing of a specific trial until the specified stop event occurs once. This is like a dynamic pause trial since background and stimulus resources can be used as in a repetition trial. The repetition time field is ignored and set to a very long time until the stop event is detected.
v2.1.8
#Timing totally re-written. Now 2 simple routines control timing of events. If the extended time manager is supported (system 7+) then MacStim will use interrupt timing (accuracy to within 20 microseconds absolute time) otherwise tics are used. The caveat is that I was able to time the fastest picture drawing possible, and it is not more than 2 ticks realistically (though faster CPUs may manage it), thus picture drop out can occur for times less than 40-50 msecs (0.05 seconds). I feel it is better to know the absolute time limits than to be fooled by rapidly cycling (but incorrectly timed) pictures. User feed back would be desirable on this point please!
#Relative timing is the default now due to the improved time manager accuracy, but absolute timing can be set to cause catch-up (on a block by block, or single trial by single trial basis) if timing strays. See the Timing & Events pane of the Preferences.
#Reaction times are now measured from the onset of the visible stimulus (text, picture or movie) rather than when MacStim tells the Mac to start drawing these. Be aware therefore that timing may be slightly shorted for this version than prior versions. If you depend upon inter-subject comparisons, you should not use this version for an unfinished experiment.
#Opening bug: when a currently open script is dirty, selecting Open from the File menu now creates a new script window and opens the script into it. If the script is not dirty, then it is replaced in the same window.
#Fixation point bug: this now correctly remains in the centre of the test window, and its color can be altered in the Preferences Display pane (thanks Keith).
#Custom picture rects bug: setting a preferred size for pictures to display will now correctly scale to the global coordinates specified (thanks Robert).
v2.1.9
#Selection menu for devices (choosing an alternate screen from the main display) has been altered to include the global coordinates of the screens available. This should make selection less confusing.
#Premature termination of a trial by detection of a correct stop event is now properly implemented, ie if this option (cmd-6 in the Experiments pane of the Preferences dialog) is checked then whenever a correct stop event occurs, MacStim will instantly start the next trial (within whatever block is currently executing).
v2.2.0
#Offsetting text using global preferences settings now works correctly (thanks Dara).
#Continuation dialog should now appear on the main screen even when extra screen(s) is(are) in use.
#Premature termination revisited & fixed so the next line correctly starts regardless of how much time is left in the total or repetition fields (thanks Monique).
v2.2.1
#With the introduction of 2.2, multiple monitor bug occurred such that offscreen gWorld was not correctly accessed during picture, text or movie display. Fixed.
